Crate tetanes_core

TetaNES Core

📖 Summary - ✨ Features - 🚧 Building - 🚀 Getting Started - ⚠️ Known Issues - 💬 Contact

Summary

photo credit for background: Zsolt Palatinus on unsplash

This is the core emulation library for TetaNES. Savvy developers can build their own custom emulation libraries or applications in Rust on top of tetanes-core.

Some community examples:

• NES Bundler - Transform your NES-game into a single executable targeting your favourite OS!
• Dappicom - Dappicom is a provable Nintendo Entertainment System emulator written in Noir and Rust.
• NESBox - NESBox’s vision is to become the preferred platform for people playing online multiplayer games, providing an excellent user experience for all its users.

Minimum Supported Rust Version (MSRV)

The current minimum Rust version is 1.78.0.

Features

• NTSC, PAL and Dendy emulation.
• Headless Mode.
• Pixellate and NTSC filters.
• Zapper (Light Gun) support.
• iNES and NES 2.0 ROM header formats supported.
• 14 supported mappers covering ~85% of licensed games.
• Game Genie Codes.
• Configurable while running.
  • Increase/Decrease speed & Fast Forward
  • Visual & Instant Rewind
  • Save & Load States
  • Battery-backed RAM saves

Building

To build the project, you’ll need a nightly version of the compiler and run cargo build or cargo build --release (if you want better framerates).

Feature Flags

• cycle-accurate - Enables cycle-accurate emulation. More CPU intensive, but supports a wider range of games requiring precise timing. Disabling may improve performance on lower-end machines. Enabled by default.
• profiling - Enables puffin profiling.

Getting Started

Below is a basic example of setting up tetanes_core with a ROM and running the emulation. For a more in-depth example see the tetanes::nes::emulation module.

use tetanes_core::prelude::*;

fn main() -> anyhow::Result<()> {
    let mut control_deck = ControlDeck::new();

    // Load a ROM from the filesystem.
    // See also: `ControlDeck::load_rom` for loading anything that implements `Read`.
    control_deck.load_rom_path("some_awesome_game.nes")?;

    while control_deck.is_running() {
      // See also: `ControlDeck::clock_frame_output` and `ControlDeck::clock_frame_into`
      control_deck.clock_frame()?;

      let audio_samples = control_deck.audio_samples();
      // Process audio samples (e.g. by sending it to an audio device)
      control_deck.clear_audio_samples();

      let frame_buffer = control_deck.frame_buffer();
      // Process frame buffer (e.g. by rendering it to the screen)

      // If not relying on vsync, sleep or otherwise wait the remainder of the
      // 16ms frame time to clock again
    }

    Ok(())
}

Known Issues

See the github issue tracker.

Contact

For issue reporting, please use the github issue tracker. You can also contact me directly at https://lukeworks.tech/contact/.

Modules

• action
  An Action is an enumerated list of possible state changes to the ControlDeck instance that allows for event handling and test abstractions such as being able to map a custom keybind to a given state change.
• apu
  NES APU (Audio Processing Unit) implementation.
• bus
  NES Memory/Data Bus implementation.
• cart
  NES cartridge implementation.
• common
  Common traits and constants.
• control_deck
  Control Deck implementation. The primary entry-point for emulating the NES.
• cpu
  6502 Central Processing Unit (CPU) implementation.
• error
  Error handling.
• fs
  Filesystem utilities for save state and compression.
• genie
  Game Genie code parsing.
• input
  Joypad and Zapper implementation.
• mapper
  Memory Mappers for cartridges.
• mem
  Memory and Bankswitching implementations.
• ppu
  NES PPU (Picture Processing Unit) implementation.
• prelude
  The prelude re-exports all the common structs/enums used for basic NES emulation.
• sys
  System-specific modules.
• time
  Time and Date methods.
• video
  Video output and filtering.